###################
Documentation Guide
###################

The documentation for the Oklahoma NG911 GIS Toolkit for ArcGIS Pro is comprised of two main pieces, namely, the API documentation for the ``ng911ok`` package and the Toolkit documentation for the ArcGIS Toolbox.

API Documentation
=================

The API documentation is written in reStructuredText_ and built with Sphinx_. It uses the `PyData Sphinx Theme`_ and that theme's corresponding version of `Sphinx Design`_.

Custom Sphinx Roles
-------------------

.. note::

   As used by Sphinx, the term "role" denotes specially-interpreted text that may be rendered differently than the text around it. This is unrelated to the ``role`` attribute of the :class:`~ng911ok.lib.config_dataclasses.NG911Field` and :class:`~ng911ok.lib.config_dataclasses.NG911FeatureClass` classes.

   In this section, the terms "Sphinx role" and "``role`` attribute" will be used to distinguish between the two.

The following custom Sphinx roles are defined:

.. list-table::
   :header-rows: 1

   * - Sphinx Role
     - Rendered
     - Corresponds To
     - Example
   * - ``ng911field``
     - :ng911field:`%Field`
     - :class:`NG911Field.role <ng911ok.lib.config_dataclasses.NG911Field.role>`
     - ``:ng911field:`field_role_attribute```
   * - ``ng911fc``
     - :ng911fc:`%Feature Class`
     - :class:`NG911FeatureClass.role <ng911ok.lib.config_dataclasses.NG911FeatureClass.role>`
     - ``:ng911fc:`feature_class_role_attribute```
   * - ``ng911domain``
     - :ng911domain:`%Domain`
     - :class:`NG911Domain.name <ng911ok.lib.config_dataclasses.NG911Domain.name>`
     - ``:ng911domain:`domain_name```
   * - ``ng911ds``
     - :ng911ds:`%Feature Dataset`
     - ``required`` or ``optional``
     - ``:ng911ds:`required```
   * - ``ng911tool``
     - :ng911tool:`Validate Geodatabase`
     - ``label`` attribute of tool classes in :mod:`ng911ok.tools`
     - ``:ng911tool:`Tool Name```

For ``:ng911field:``, ``:ng911fc:``, ``:ng911domain:``, and ``:ng911ds:``, if the text starts with a percent sign (``%``), that character itself will be removed, but whatever text that follows it will be preserved; this functionality is intended to be used only for demonstration purposes (e.g., to produce the contents of the "Rendered" column in the table above).

In the case of fields and feature classes, the provided ``role`` attribute will be replaced with the ``name`` attribute. This ensures that the correct field or feature class name will always be reflected when using these custom Sphinx roles, even if the ``name`` attributes change in a future version of the Standards.

In the case of tools, the rendered output will link to the corresponding tool class in :mod:`ng911ok.tools`, but the text itself will not be changed.

These custom Sphinx roles are implemented in the modules in ``/_ext`` and the stylesheets are located in ``/_static`` (where ``/`` denotes the Sphinx source root).

Toolkit Documentation
=====================

The Toolkit documentation is written in Markdown.

Using `Visual Studio Code`_ with the `Markdown All in One`_ extension, the documentation can be exported as HTML every time the Markdown files are saved.

.. _reStructuredText:
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html

.. _Sphinx:
   https://www.sphinx-doc.org/en/master/

.. _PyData Sphinx Theme:
   https://pydata-sphinx-theme.readthedocs.io/en/stable/

.. _Sphinx Design:
   https://sphinx-design.readthedocs.io/en/pydata-theme/

.. _Visual Studio Code:
   https://code.visualstudio.com/

.. _Markdown All in One:
   https://marketplace.visualstudio.com/items/?itemName=yzhang.markdown-all-in-one